home *** CD-ROM | disk | FTP | other *** search
/ TPUG - Toronto PET Users Group / TPUG Users Group CD / TPUG Users Group CD.iso / CRS / crs49.d81 / hack7b.sfx / hack#7c.txt next >
Text File  |  1990-02-12  |  40KB  |  863 lines
  1.  
  2.  
  3. ┘OU CAN DO IT ON THE SCREEN, HOW ABOUT BORDERS ?
  4.  
  5. ┬ECAUSE YOU CANNOT GET CHARACTERS TO THE BORDER, YOU MIGHT THINK THAT IT
  6. IS IMPOSSIBLE TO MAKE A TECH-TECH EFFECT IN THE BORDERS. ╔T TAKES SO
  7. MUCH TIME TO CHANGE SPRITE X-COORDINATES, THAT YOU CAN CHANGE ONLY SOME
  8. OF THEM. ╘HERE IS TIME FOR FIVE SPRITE MOVES, IF YOU DO NOT NEED TO
  9. CHANGE THE MOST SIGNIFICANT (9TH) BIT OF THE X-COORDINATE. ╧N THE OTHER
  10. HAND, YOU COULD DESIGN THE MOVEMENTS DIRECTLY TO THE SPRITES AND THEN
  11. JUST CHANGE THE IMAGES, BUT THEN THE MOVEMENTS WOULD BE CONSTANT.
  12.  
  13. ╚OWEVER, THERE IS ONE TRICK YOU CAN USE TO GET ALL OF THE SPRITES ON THE
  14. SCREEN, WITH VARIABLE MOVEMENTS AND COLOR BARS ETC. ┘OU DO NOT CHANGE
  15. THE X-COORDINATES, BUT THE DATA ITSELF ON EACH SCAN LINE. ╔N FACT YOU
  16. CHANGE THE SPRITE IMAGE POINTERS. ╘HERE IS MULTIPLE SPRITE PICTURES,
  17. WHERE THE GRAPHICS IS SHIFTED HORIZONTALLY, JUST LIKE THE NORMAL
  18. TECH-TECH CHARSETS. ┬ECAUSE OF THIS, THE SPRITES HAVE TO BE PLACED SIDE
  19. BY SIDE. ╬O GAPS ARE ALLOWED. ┬Y CHANGING THE IMAGE POINTERS YOU CAN GET
  20. THE GRAPHICS TO MOVE HORIZONTALLY ON EACH LINE AS YOU WISH. ╫ITH
  21. MULTICOLOR SPRITES YOU HAVE TO REMEMBER THAT ONE PIXEL CORRESPONDS TO
  22. TWO BITS - THE MOVEMENT IS NOT SO SMOOTH.
  23.  
  24. ╫AIT ! ╚OW COME THERE IS ENOUGH TIME TO CHANGE THE SPRITE POINTERS, WHEN
  25. THERE IS NOT TIME TO CHANGE THE COORDINATES ? ╘HIS IS ANOTHER POINTER
  26. TRICK. ╓╔├ READS THE SPRITE IMAGE POINTERS FROM THE END OF THE CURRENT
  27. VIDEO MATRIX, NORMALLY $07F8. ┘OU JUST HAVE TO CHANGE THE VIDEO MATRIX
  28. POINTER ($─018) TO CHANGE ALL OF THE IMAGE POINTERS. ╘HIS TAKES ONLY
  29. EIGHT CYCLES AND THERE IS PLENTY OF TIME LEFT FOR OTHER EFFECTS ON EACH
  30. SCAN LINE. ╔F YOU USE ONLY ONE VIDEO BANK, YOU CAN GET THE SPRITE
  31. PICTURE TO 16 DIFFERENT PLACES. ╘HIS ALLOWS ALSO ANOTHER KIND OF
  32. EFFECTS, JUST USE YOUR IMAGINATION.
  33.  
  34. --------------------------------------------------------------------------
  35. ╘ECH-TECH DEMO PROGRAM (╨┴╠)
  36.  
  37. ┬┴╬╦=   $96     ; ╘HE VALUE OF THE VIDEO BANK REGISTER (├╔┴2) IN THE TECH-AREA
  38. ┌╨=     $╞┬     ; ┌ERO PAGE FOR INDIRECT ADDRESSING
  39. ╙╘┴╥╘=  $4400   ; ╙TART OF THE CHARSETS (WE USE INVERTED CHARS)
  40. ╙├╥┼┼╬= $4000   ; ╨OSITION OF THE VIDEO MATRIX
  41. ╙╚╔╞╘╠= $├╞00   ; X-SHIFT, LOWEST 3 BITS
  42. ╙╚╔╞╘╚= $├┼00   ; X-SHIFT, HIGHEST 3 BITTID (MULTIPLIED WITH TWO)
  43. ╨╧╔╬╘┼╥= $033├  ; ╨OINTER TO SHIFT-TABLE
  44. ╓┴╠╒┼=  $033─   ; ╙HIFT NOW
  45. ╙╨┼┼─=  $033┼   ; ╙HIFT CHANGE
  46.  
  47. *= $├000  ; ╙TART ADDRESS..
  48.  
  49. ╔╬╔╘    ╙┼╔             ; ─ISABLE INTERRUPTS
  50.         ╠─┴ #$7╞
  51.         ╙╘┴ $─├0─       ; ─ISABLE TIMER INTERRUPT
  52.         ╠─┴ #$81
  53.         ╙╘┴ $─01┴       ; ┼NABLE RASTER INTERRUPT
  54.         ╠─┴ #<╔╥╤
  55.         ╙╘┴ $0314       ; ╧UR OWN INTERRUPT HANDLER
  56.         ╠─┴ #>╔╥╤
  57.         ╙╘┴ $0315
  58.         ╠─┴ #49         ; ╘HE INTERRUPT TO THE LINE BEFORE THE FIRST BAD LINE
  59.         ╙╘┴ $─012
  60.         ╠─┴ #$1┬
  61.         ╙╘┴ $─011       ; 9TH BIT OF THE RASTER COMPARE
  62.  
  63.         ╠─┘ #0
  64.         ╠─╪ #$40
  65.         ╙╘╪ ┌╨+1
  66.         ╙╘┘ ┌╨
  67.         ╘┘┴
  68. ╠╧╧╨0   ╙╘┴ (┌╨),┘      ; ├LEAR THE WHOLE VIDEO BANK ($4000-7╞╞╞)
  69.         ╔╬┘
  70.         ┬╬┼ ╠╧╧╨0
  71.         ╔╬├ ┌╨+1
  72.         ┬╨╠ ╠╧╧╨0
  73.  
  74.         ╠─┴ #>╙╘┴╥╘
  75.         ╙╘┴ ┌╨+1
  76.         ╠─┴ #$32        ; ├HARACTER ╥╧═ TO ADDRESS SPACE ($─000-)
  77.         ╙╘┴ $01
  78. ╠╧╧╨1   ╘┘┴             ; (┘-REGISTER IS ZERO INITIALLY)
  79.         ╠╙╥
  80.         ╠╙╥
  81.         ╠╙╥
  82.         ╘┴╪
  83.         ╠─┴ ╘┼╪╘,╪      ; ╫HICH CHAR TO PLOT ?
  84.         ┴╙╠             ; ╙OURCE
  85.         ┴╙╠
  86.         ┴╙╠
  87.         ╘┴╪             ; LOW BYTE TO ╪
  88.         ╠─┴ #$─0
  89.         ┴─├ #0          ; HIGH BYTE (ONE BIT) TAKEN INTO ACCOUNT
  90.         ╙╘┴ ╠╧╧╨2+2 ; ╙ELF-MODIFYING AGAIN..
  91. ╠╧╧╨2   ╠─┴ $─000,╪
  92.         ╙╘┴ (┌╨),┘
  93.         ╔╬╪
  94.         ╔╬┘
  95.         ╘╪┴
  96.         ┴╬─ #7
  97.         ┬╬┼ ╠╧╧╨2       ; ├OPY ONE CHAR
  98.         ├╨┘ #0
  99.         ┬╬┼ ╠╧╧╨1       ; ├OPY 32 CHARS (256 BYTES)
  100.         ╠─┴ #$37        ; ═EMORY CONFIGURATION BACK TO NORMAL
  101.         ╙╘┴ $01
  102.  
  103. ╠╧╧╨3   ╠─┴ ╙╘┴╥╘,┘       ; ├OPY THE DATA TO EACH CHARSET, SHIFTED BY ONE
  104.         ╙╘┴ ╙╘┴╥╘+2056,┘  ;  POSITION TO THE RIGHT
  105.         ╙╘┴ ╙╘┴╥╘+4112,┘
  106.         ╙╘┴ ╙╘┴╥╘+6168,┘
  107.         ╙╘┴ ╙╘┴╥╘+8224,┘
  108.         ╙╘┴ ╙╘┴╥╘+10280,┘
  109.         ╙╘┴ ╙╘┴╥╘+12336,┘
  110.         ╙╘┴ ╙╘┴╥╘+14392,┘
  111.         ╔╬┘
  112.         ┬╬┼ ╠╧╧╨3
  113.         ╠─┴ #0          ; ├LEAR THE POINTER, VALUE AND SPEED
  114.         ╙╘┴ ╨╧╔╬╘┼╥
  115.         ╙╘┴ ╓┴╠╒┼
  116.         ╙╘┴ ╙╨┼┼─
  117.  
  118. ╠╧╧╨4   ╘┘┴             ; (┘ WAS ZERO)
  119.         ╧╥┴ #$80        ; ╒SE THE INVERTED CHARS
  120.         ╙╘┴ ╙├╥┼┼╬,┘    ; ╙ET THE CHARACTER CODES TO VIDEO MATRIX
  121.         ╙╘┴ ╙├╥┼┼╬+40,┘
  122.         ╙╘┴ ╙├╥┼┼╬+80,┘
  123.         ╙╘┴ ╙├╥┼┼╬+120,┘
  124.         ╙╘┴ ╙├╥┼┼╬+160,┘
  125.         ╙╘┴ ╙├╥┼┼╬+200,┘
  126.         ╙╘┴ ╙├╥┼┼╬+240,┘
  127.         ╙╘┴ ╙├╥┼┼╬+280,┘
  128.         ╠─┴ #239        ; LEAVE THE LAST LINE EMPTY
  129.         ╙╘┴ ╙├╥┼┼╬+320,┘
  130.         ╔╬┘
  131.         ├╨┘ #40
  132.         ┬╬┼ ╠╧╧╨4       ; ╠OOP UNTIL THE WHOLE AREA IS FILLED
  133.         ├╠╔             ; ┼NABLE INTERRUPTS
  134.         ╥╘╙
  135.  
  136. ╔╥╤     ╠─┴ #┬┴╬╦       ; ├HANGE THE VIDEO BANK, SOME TIMING
  137.         ╙╘┴ $──00
  138.         ╬╧╨
  139.         ╬╧╨
  140.  
  141.         ╠─┘ ╨╧╔╬╘┼╥     ; ┘-REGISTER WILL POINT TO X-SHIFT
  142.         ╩═╨ ┬┴─         ; NEXT LINE IS A BAD LINE
  143. ╠╧╧╨5   ╬╧╨
  144. ╠╧╧╨6   ╠─┴ ╙╚╔╞╘╠,┘    ; ─O THE SHIFT
  145.         ╙╘┴ $─016       ; 3 LOWEST BITS
  146.         ╠─┴ ╙╚╔╞╘╚,┘
  147.         ╙╘┴ $─018       ; ANOTHER 3 BITS
  148.         ╬╧╨ : ╬╧╨ : ╬╧╨ : ╬╧╨ : ╬╧╨ : ╬╧╨ ; WASTE SOME TIME
  149.         ╬╧╨ : ╬╧╨ : ╬╧╨ : ╬╧╨ : ╬╧╨ : ╬╧╨
  150.         ╬╧╨ : ╬╧╨ : ╬╧╨
  151.         ╠─┴ $─012       ; CHECK IF IT IS TIME TO STOP
  152.         ├═╨ #$78
  153.         ┬╨╠ ╧╓┼╥
  154.         ╔╬┘   ; NEXT POSITION IN TABLE
  155.         ─┼╪
  156.         ┬╬┼ ╠╧╧╨5       ; ╬O BAD LINE, LOOP
  157. ┬┴─     ╠─┴ ╙╚╔╞╘╠,┘    ; ╘HIS IS A BAD LINE, A BIT MORE HURRY
  158.         ╙╘┴ $─016
  159.         ╠─┴ ╙╚╔╞╘╚,┘
  160.         ╙╘┴ $─018
  161.         ╔╬┘
  162.         ╠─╪ #7          ; ╬EW BAD LINE COMING UP
  163.         ╩═╨ ╠╧╧╨6
  164.  
  165. ╧╓┼╥    ╠─┴ #$97        ; ╓IDEO BANK TO 'NORMAL'
  166.         ╙╘┴ $──00
  167.         ╠─┴ #22         ; ╙AME WITH THE CHARSET
  168.         ╙╘┴ $─018
  169.         ╠─┴ #8          ; AND THE HORIZONTAL SCROLL REGISTER
  170.         ╙╘┴ $─016
  171.  
  172.         ╠─┴ $─├00       ; ╠ET'S CHECK THE JOYSTICKS
  173.         ┴╬─ $─├01
  174.         ╘┴╪
  175.         ╠─┘ ╙╨┼┼─
  176.         ┴╬─ #8          ; ╘URNED RIGHT, ADD SPEED
  177.         ┬╬┼ ┼╔╨
  178.         ╔╬┘
  179.         ├╨┘ #4          ; ─ON'T STORE, TOO MUCH SPEED
  180.         ┬╨╠ ┼╔╨
  181.         ╙╘┘ ╙╨┼┼─
  182. ┼╔╨     ╘╪┴
  183.         ┴╬─ #4          ; ╘URNED LEFT
  184.         ┬╬┼ ╒╠╧╙
  185.         ─┼┘
  186.         ├╨┘ #$╞├        ; ╘OO MUCH ?
  187.         ┬═╔ ╒╠╧╙
  188.         ╙╘┘ ╙╨┼┼─
  189. ╒╠╧╙    ╠─┴ ╓┴╠╒┼       ; ┴DD SPEED TO VALUE (SIGNED)
  190.         ├╠├
  191.         ┴─├ ╙╨┼┼─
  192.         ┬╨╠ ╧╦
  193.         ╠─┴ ╙╨┼┼─       ; ┬ANGED TO THE SIDE ?
  194.         ┼╧╥ #$╞╞
  195.         ├╠├
  196.         ┴─├ #1
  197.         ╙╘┴ ╙╨┼┼─
  198.         ╠─┴ ╓┴╠╒┼
  199. ╧╦      ╙╘┴ ╓┴╠╒┼
  200.         ╠╙╥             ; ╓ALUE IS TWICE THE SHIFT
  201.         ╘┴╪             ; ╥EMEMBER THE SHIFT
  202.         ┴╬─ #7          ; LOWEST 3 BITS
  203.         ╧╥┴ #8          ; (SCREEN 40 CHARS WIDE)
  204.         ╠─┘ ╨╧╔╬╘┼╥
  205.         ╙╘┴ ╙╚╔╞╘╠,┘
  206.         ╘╪┴
  207.         ╠╙╥
  208.         ╠╙╥
  209.         ╠╙╥             ; HIGHEST 3 BITS TOO
  210.         ┴╙╠             ;  MULTIPLICATED BY TWO
  211.         ╙╘┴ ╙╚╔╞╘╚,┘
  212.         ─┼├ ╨╧╔╬╘┼╥
  213.  
  214.         ╠─┴ #1          ; ┴CK THE INTERRUPT
  215.         ╙╘┴ $─019
  216.         ╩═╨ $┼┴31       ; ╘HE NORMAL INTERRUPT ROUTINE
  217.  
  218. ╘┼╪╘    ╙├╥ "╘╚╔╙ ╔╙ ╘┼├╚-╘┼├╚ ╞╧╥ ├=64 ┬┘ ═┼" ; ╘EST TEXT
  219.                         ; ╙├╥ CONVERTS TO SCREEN CODES
  220.  
  221. --------------------------------------------------------------------------
  222. ┬ASIC LOADER FOR THE ╘ECH-TECH DEMO PROGRAM (╨┴╠)
  223.  
  224. 1 ╙=49152
  225. 2 ─┼╞╞╬╚(├)=├-48+7*(├>64)
  226. 3 ├╚=0:╥┼┴─┴$,┴:╨╥╔╬╘┴$:╔╞┴$="┼╬─"╘╚┼╬╨╥╔╬╘"<CLR>":╙┘╙49152:┼╬─
  227. 4 ╞╧╥╞=0╘╧31:╤=╞╬╚(┴╙├(═╔─$(┴$,╞*2+1)))*16+╞╬╚(┴╙├(═╔─$(┴$,╞*2+2)))
  228. 5 ├╚=├╚+╤:╨╧╦┼╙,╤:╙=╙+1:╬┼╪╘:╔╞├╚=┴╘╚┼╬3
  229. 6 ╨╥╔╬╘"├╚┼├╦╙╒═ ┼╥╥╧╥":┼╬─
  230. 100 ─┴╘┴ 78┴97╞8─0──├┴9818─1┴─0┴9┴─8─1403┴9├08─1503┴9318─12─0┴91┬8─11─0┴0, 3802
  231. 101 ─┴╘┴ 00┴24086╞├84╞┬9891╞┬├8─0╞┬┼6╞├10╞7┴94485╞├┴9328501984┴4┴4┴┴┴┬─5┼, 4749
  232. 102 ─┴╘┴ ├10┴0┴0┴┴┴┴9─069008─4┼├0┬─00─091╞┬┼8├88┴2907─0╞4├000─0──┴9378501, 4128
  233. 103 ─┴╘┴ ┬9004499084├99105499185├99206499286├99307499387├├8─0┼5┴9008─3├03, 3258
  234. 104 ─┴╘┴ 8─3─038─3┼0398098099004099284099504099784099┴04099├84099╞0409918, 3236
  235. 105 ─┴╘┴ 41┴9┼╞994041├8├028─0─┬5860┴9968─00──┼┴┼┴┴├3├034├┼1├0┼┴┬900├╞8─16, 4464
  236. 106 ─┴╘┴ ─0┬900├┼8─18─0┼┴┼┴┼┴┼┴┼┴┼┴┼┴┼┴┼┴┼┴┼┴┼┴┼┴┼┴┼┴┴─12─0├9781016├8├┴─0, 5850
  237. 107 ─┴╘┴ ─9┬900├╞8─16─0┬900├┼8─18─0├8┴2074├┬┬├0┴9978─00──┴9168─18─0┴9088─, 4132
  238. 108 ─┴╘┴ 16─0┴─00─├2─01─├┴┴┴├3┼032908─008├8├00410038├3┼038┴2904─00888├0╞├, 3160
  239. 109 ─┴╘┴ 30038├3┼03┴─3─03186─3┼03100┼┴─3┼0349╞╞1869018─3┼03┴─3─038─3─034┴, 2139
  240. 110 ─┴╘┴ ┴┴29070908┴├3├039900├╞8┴4┴4┴4┴0┴9900├┼├┼3├03┴9018─19─04├31┼┴1408, 2759
  241. 111 ─┴╘┴ 091320091320140503082─1405030820060╞1220033─3634200219200─050╞12, 652
  242. 200 ─┴╘┴ ┼╬─,0
  243.  
  244. --------------------------------------------------------------------------
  245. ╒UENCODED ├64 EXECUTABLE VERSION OF THE DEMO PROGRAM (╨┴╠)
  246.  
  247. BEGIN 644 TECH.64
  248. ═└0@-"└$└4[(╘.3$╒,@└╞"└(└┼╩5(*$,╔╠─.╦-#┬╩-┌╨╚0[$╓-"─└7└@#└$-(╩
  249. ═╠├└┌┴╘$─+$$┌╞4$─.╚═!)+(┬14┘$(╩>9(├╙7╥,╟4╤3╪\╨\╙2/┬(┌╟├0┘,34╥;
  250. ═.╚└└─╨@$└(%&╠├"─,╙$┌4;*┼2"├&*,╚╚020╠1╩╨╥╩├$╔*2╞╠,3:╩╔4@╚╤┬├*1
  251. ═*$$─+$:╠,╩╚╥*2─╔└+0(!0!#2+)#2*╔1.╔=3+%$┌4[)3╩├$┌@├╩+0╘┬╥0:<╙?
  252. ═└,╨(!@"9(─-(14-+4╒5-($524─]2(├╩└└!─)9└"#(#<╪03─╫1├┴$,$1$0╘$┘╬
  253. ═.#$╪1#%!1#!!.4%$.$0╤-#└╙03┼#,#┴$,34╨,╘$┘,╙$╪1#$╥1#!!.3%".$0╤+
  254. ═,40╨03└╠(#,╪,#(└9@┼┼└(,@,#!!,├0╨.#9&0╙@╘1─(┘.#─╤1─)#.$0╨1─)%╟
  255. ═-─9#,3!&-╘$┘-#0╪-49#03─╙,├@╒,#$┘.#1!-$$╘04%!0─0╒12╨@-#<╘.0"╙+
  256. ═"68└@╥!#,3!!,$$╨04%!03┼$,#8┘,#└╪1#1%0╙!"1#└╨1#└┘,49"13┴#.#┴!]
  257. ═,├─╨-╘0╨1├1#,#└╨1#!$1$$┘,╙<╪-3└╤+"└╘,3(╪└└└*9╨"#($(┘,#└╘-#─┘┼
  258. ═,#@╘0╙─┘,3└╒-#─┘,3@╒0╙─┘,├└╓-#─┘,├@╓0╙─┘,╙└╫-#─┘,╙@╫0╘,╪1#!%,
  259. ═-4$┘,#└╪1#-#,#,╠(#,╥-3@└30╔╚└(,@.$0╙1#└╙.$0╙13└╙.3@╨.3@╨.3─╨╒
  260. ═,#0╨.3─╥.#0╨.3─╒,#0╨.3─╫.#0╨.3┼!,#0╨.3┼#.#0╨.3┼&,#0╨.3─╤."╨@?
  261. ═,╙(╙-@":"╞─└@╥└╘,4$┘148┘.30╨-#%#.$,╨,├┴$,$1"-3@╓,$$┘.38╪1#└╨-
  262. ═1$1%045!04,╙0╙└╙-$-%,4,╨14%".3└╨0╘8╪1#$╓+"└╘-#8╘└.<*:@"#($0╨╬
  263. ═0├─╨,$-%.$0╤.$0╨14%%045!14%%045!14%%045!14%%045!14%%045!040╤,
  264. ═,─0╨0╙─╫.#$╨,39#.$-!1#└╠(#4╪-3└└-└═╦└(,@1#┼".3└╨0╘8╪1#$╓1#!"╤
  265. ═.3└╨0╘4╪1#$╪1#!#.$$╥,#<╘0╘)"0╙!!.3─╫.$0╨,$1$03─╤-├┴$,3┴$,$$┘_
  266. ═,#@╪1"╨@-#$╙,@"!"╓╨└@╥└╤-─0╨040╨,$1#,─0╨,41#04%!0╙-%,#,╥.3└╪╬
  267. ═1#└╨.$,╪0╙└╨-#$╨,#,╪0╙-%,#,╪03(┘,#1$,#└╪.#┴#,$9#+"└╙,38╨└,╪+'
  268. ═;0"#(#,╨,#,╪0╙-%,#-!1#-$,#,╤.#9$,╘4╨,╙$╨,$5!1#-%,#,╘.49&,3@╓7
  269. ═.3└╤.$0╙13└╙040╙1#└╙.$0╙1#└╙-$$╠(#(╤,╙─└&╨╤╬└(,@04$╥.3└╫,#─╨;
  270. ═.$%#,╘,╨,╙─┘,#!#1├┴!-$$╘031!,$$┘.3└╨0╘5#13-#,#-!.3└╤.$0╤.40╨╔
  271. ═-$,╙,45!,30╨."╨@,├<╒.0!╟#&\└@╥└╨.3$╙,├└╨.3$╙,├└╤-#└╒,#,╨.#)$_
  272. ═,30╨-3└╙,#@╥,#└╓,$8╤,├(╨,#,╙1#,╓,╙0╥,#└╥,3─╥,#!$,#4╨1├$╥+"└╓&
  273. 4-3(└<╨╙(└(,@14┘$+#└└└└└└└└╚╙!
  274. └└
  275. END
  276.  
  277. =============================================================================
  278. ┴├┼-128/64 ╨╥╧╟╥┴══┼╥'╙ ╥┼╞┼╥┼╬├┼ ╟╒╔─┼ (VERSION 0.9, FOR ╥ELEASE #10)
  279. BY ├RAIG ┬RUCE  <CSBRUCE@CCNGA.UWATERLOO.CA>
  280.  
  281. 1. ╔╬╘╥╧─╒├╘╔╧╬
  282.  
  283. ┴├┼ IS A PROGRAM FOR THE ├OMMODORE 128 AND ├OMMODORE 64 THAT PROVIDES A
  284. COMMAND SHELL ENVIRONMENT THAT IS SIMILAR TO THAT OF ╒NIX.  ╔T IS STILL
  285. IN THE DEVELOPMENT STAGE, BUT ENOUGH OF IT IS COMPLETE TO BE USEFUL.
  286. ┬╘╫, "┴├┼" MEANS "┴DVANCED ├OMPUTING ┼NVIRONMENT" (WELL, ADVANCED FOR
  287. THE 128/64).
  288.  
  289. ╙O WHAT IS ┴├┼ ALL ABOUT?  ╫ELL, ORIGINALLY ╔ TRIED A VERY AMBITIOUS
  290. PROJECT OF WRITING A MULTITASKING OPERATING SYSTEM FOR THE 128.  ╔T GOT
  291. IT PARTIALLY WORKING, BUT IT WAS MUCH TOO FRAGILE AND INCOMPLETE TO BE
  292. RELEASED.  ╔T WAS A WHITE-ELEPHANT PROJECT.  ╙O, THEN THEN IT CAME TO ME
  293. THAT ╔ WAS AIMING MUCH TOO HIGH.  ╫HAT ╔ NEEDED WAS A MUCH SIMPLER
  294. SYSTEM, ONE THAT WOULD GIVE THE TYPE OF PROGRAMMING INTERFACE AND
  295. BUILT-IN FEATURES THAT ╔ WANTED, BUT ONE THAT WAS CLOSE ENOUGH TO THE
  296. ├OMMODORE ╦ERNAL THAT IT WOULD NOT REQUIRE MUCH OF A PROGRAMMING EFFORT
  297. TO HACK TOGETHER A MINIMAL IMPLEMENTATION.  ┴ND THUS, THERE WAS ┴├┼-128
  298. ╥ELEASE #1.  ┴ND ╔ SAW IT WAS GOOD.
  299.  
  300. ╫HAT ╔ WANTED WAS A SYSTEM THAT WOULD BE EASIER TO PROGRAM THAN THE
  301. ├OMMODORE ╦ERNAL WITH ALL ITS WEIRD AND WONDERFUL DEVICE TYPES,
  302. NON-EXISTENT MEMORY MANAGEMENT, AND SINGLE-APPLICATION DESIGN.  ╘HE
  303. FIRST IMPORTANT FEATURE OF THIS ENVIRONMENT WAS TO BE ABLE TO PASS
  304. ARGUMENTS FROM A COMMAND LINE TO AN APPLICATION PROGRAM BY TYPING THEM
  305. ON THE COMMAND LINE OF THE SHELL.  ╔T IS SO ANNOYING TO LOAD UP A
  306. PROGRAM IN ┬┴╙╔├, RUN IT, AND HAVE IT ASK YOU FOR FILENAMES IN SOME
  307. HIGHLY INCONVENIENT WAY.
  308.  
  309. ┴NOTHER IMPORTANT SYSTEM FEATURE IS TO MAKE NEAR AND FAR MEMORY
  310. MANAGEMENT PART OF THE SYSTEM, AND TO MAKE FAR MEMORY CONVENIENT TO USE
  311. FOR STORING MASSIVELY BULKY DATA.  ┴ND SO IT WAS.  ┴LSO, WE WANT TO USE
  312. CUSTOM DEVICE DRIVERS.  ├OMMODORE DIDN'T REALLY COME THROUGH WITH THE
  313. DEVICE DRIVERS IT PROVIDED.  ╘HEY ARE ALL ╥┼┴╠╠┘ ╙╠╧╫.  ┴ND SO THAT WAS,
  314. ALSO, ALTHOUGH MORE CUSTOM DEVICE DRIVERS ARE NEEDED.  ╫E WANT TO HAVE
  315. THE CAPABILITY OF MAKING PROGRAMS WORK TOGETHER, RATHER THAN HAVING
  316. PROGRAMS THAT ARE TOTALLY INCOMPATIBLE.  ╘HIS FUNCTIONALITY IS STILL
  317. UNDER CONSTRUCTION.  ╨ROGRAMS WILL WORK TOGETHER IN THIS UNI-TASKING
  318. ENVIRONMENT BY ALLOWING A PROGRAM TO EXECUTE ANOTHER PROGRAM AS A
  319. SUB-TASK, AND THEN HAVING CONTROL RETURN TO THE CALLING PROGRAM UPON
  320. EXIT.  ╞INALLY, WE WANT SOME GOOD QUALITY APPLICATIONS AND A POWERFUL
  321. COMMAND SHELL.  ╘HIS IS STILL BEING WORKED ON AND PROGRESS IS COMING
  322. SLOWLY.  ╧H, ALMOST FORGOT; WE ALSO WANT ALL PROGRAMS TO WORK ON BOTH
  323. THE ├64 AND ├128, AND THEY DO.
  324.  
  325. ╘HIS DOCUMENTATION REFERS TO ┴├┼ RELEASE #10, WHICH HAS NOT BEEN
  326. RELEASED YET (OR EVEN PROGRAMMED).  ╔N FACT, THE CURRENT RELEASE IS #9.
  327. ╥ELEASE #10 WILL BE SPRUCED UP FROM THE INSIDE OUT TO SUPPORT THE SYSTEM
  328. INTERFACE DESCRIBED IN THIS DOCUMENT.  ╘HE CURRENT RELEASE IS NOT BEING
  329. DESCRIBED, BECAUSE SOME OF ITS FEATURES ARE NOT THE BEST THEY COULD
  330. POSSIBLY BE.  ╬OTE, HOWEVER, THAT THE BASIC FEATURES, LIKE "OPEN",
  331. "READ", "DIRREAD", AND ARGV ARE NOT GOING TO CHANGE.  ╬OTE ALSO THAT THE
  332. VERSION NUMBER OF THIS "╨.╥.╟." IS 0.9.  ╘HIS IS BECAUSE THIS IS THE
  333. FIRST INCARNATION OF THIS DOCUMENT AND, CONSIDERING ITS NATURE, IS BOUND
  334. TO HOLD A LARGE NUMBER OF SMALL ERRORS.
  335.  
  336. 2. ╙┘╙╘┼═ ╔╬╘┼╥╞┴├┼
  337.  
  338. ╘HIS SECTION DESCRIBES THE INTERFACE BETWEEN USER PROGRAMS AND THE ┴├┼
  339. KERNEL. ╔ AM VERY CAREFUL THROUGHOUT THIS INTERFACE SPECIFICATION ABOUT
  340. REVEALING ANY INTERNAL DETAILS THAT YOU DO NOT STRICTLY NEED TO KNOW.
  341. ╘HE INTERFACE WITH ┴├┼ IS NOT SPECIFIED IN TERMS OF ABSOLUTE ADDRESSES;
  342. TO AID IN PORTABILITY AND EXTENSIBILITY, ALL INTERFACES ARE SPECIFIED IN
  343. TERMS OF SYMBOLIC ASSEMBLER LABELS.  ┴LL OF THE ┴├┼ CODE IS CURRENTLY
  344. WRITTEN FOR THE ┬UDDY-128 ASSEMBLER. ┴LSO, BECAUSE THESE INTERFACE
  345. ABSOLUTE ADDRESSES ARE SUBJECT TO CHANGE FROM VERSION TO VERSION OF THE
  346. KERNEL, EXECUTABLES COMPILED FOR USE WITH AN OLD VERSION OF ┴├┼ MAY NOT
  347. WORK WITH A NEW VERSION.
  348.  
  349. 2.1. ┌┼╥╧-╨┴╟┼ ╓┴╥╔┴┬╠┼╙
  350.  
  351. ╘HERE ARE FOUR ZERO-PAGE VARIABLES USED FOR PASSING ARGUMENTS IN MOST
  352. SYSTEM CALLS.  ╘HEY ARE AS FOLLOWS:
  353.  
  354. ╙┘═┬╧╠   ┬┘╘┼╙   ─┼╙├╥╔╨╘╔╧╬
  355. -------  -----   -----------
  356. ZP           2   ZEROPAGE POINTER
  357. ZW           2   ZEROPAGE WORD
  358. MP           4   MEMORY POINTER
  359. SYSWORK     16   SYSTEM WORK AREA / ARGUMENTS
  360.  
  361. ╘HE FIRST TWO, "ZP" AND "ZW" ARE USED IN MOST CALLS.  ╘HEY STORE SIMPLE
  362. 16-BIT VALUES; "ZP" USUALLY STORES POINTERS TO STRINGS IN ╥┴═0 MEMORY.
  363. ╘HE "MP" VARIABLE IS 32-BITS IN LENGTH AND IS USED EXCLUSIVELY FOR
  364. PASSING FAR MEMORY POINTERS FOR USE WITH THE FAR MEMORY ROUTINES.  ┴LL
  365. THREE OF THESE VARIABLES WILL REMAIN UNCHANGED INSIDE OF SYSTEM CALL
  366. UNLESS THEY WILL CONTAIN A RETURN VALUE.  "SYSWORK" IS A 16-BYTE ARRAY
  367. USED MAINLY WHEN THERE ARE TOO MANY ARGUMENTS FOR OTHER VARIABLES TO
  368. HOLD, AND ALL NON-INPUT AND NON-OUTPUT BYTES OF "SYSWORK" ARE SUBJECT TO
  369. CHANGE BY THE KERNEL.  ┴LL INPUT ARGUMENTS PLACED IN THE "SYSWORK"
  370. LOCATIONS WILL BE PRESERVED UNLESS OTHERWISE INDICATED. [╬OTE: ╔N
  371. ╥ELEASE #9, "ZP" TOOK ON THE ROLLS OF BOTH "ZP" AND "MP"].
  372.  
  373. 2.2. ╙┘╙╘┼═ ╓┴╥╔┴┬╠┼╙
  374.  
  375. ╘HERE ARE SEVERAL NON-ZEROPAGE VARIABLES FOR STORING SYSTEM STATUS AND
  376. RETURN VALUES:
  377.  
  378. ╙┘═┬╧╠          ┬┘╘┼╙   ─┼╙├╥╔╨╘╔╧╬
  379. ----------      -----   -----------
  380. ERRNO               1   ERROR NUMBER CODE RETURNED BY FAILED SYSTEM CALLS
  381. ACE╔─               2   PROOF THAT USER PROGRAM IS RUNNING ON TOP OF ┴├┼
  382. ACE┴RGC             2   ARGUMENT COUNT FOR CURRENT PROCESS
  383. ACE┴RGV             2   ARGUMENT VECTOR ADDRESS FOR CURRENT PROCESS
  384. ACE═EM╘OP           2   HIGHEST ADDRESS, PLUS ONE, THAT USER PROG CAN USE
  385. ACE╙HELL╨ATH        2   PTR TO STORAGE FOR SEARCH PATH FOR EXECUTABLE PROGRAMS
  386. ACE╙HELL┴LIAS       2   PTR TO STORAGE FOR SHELL COMMAND ALIASES
  387. ACE├UR─IR╬AME       2   PTR TO STORAGE FOR THE CURRENT DIRECTORY NAME
  388. ACE┼XIT─ATA         2   PTR TO STORAGE FOR EXIT STATUS FROM THE LAST CALLED PRG
  389. ACE─IRENT┬UFFER <NEXT>  STORAGE FOR DIRECTORY ENTRIES READ FROM DISK
  390. ACE─IRENT╠ENGTH     -   REALLY A CONSTANT: LENGTH IN BYTES OF "ACE─IRENT┬UFFER"
  391. ACE─IRENT┬YTES      4   BYTES IN FILE (USUALLY INEXACT)
  392. ACE─IRENT─ATE       8   DATE OF FILE IN "┘┘:┘┘:══:──:╚╚:══:╙╙:╘╫" FORMAT
  393. ACE─IRENT╘YPE       4   TYPE OF FILE IN NULL-TERMINATED STRING
  394. ACE─IRENT╞LAGS      1   FLAGS OF FILE, "DRWX*-ET" FORMAT
  395. ACE─IRENT╬AME╠EN    1   LENGTH OF NAME OF FILE
  396. ACE─IRENT╬AME      17   NULL-TERMINATED NAME OF FILE
  397.  
  398. ┼╥╥╬╧: "ERRNO" IS USED TO RETURN ERROR CODES FROM SYSTEM CALLS.  ╫HEN A
  399. SYSTEM CALL ENDS IN ERROR, IT SETS THE CARRY FLAG TO "1", PUTS THE ERROR
  400. CODE IN "ERRNO", AND RETURNS TO THE USER PROGRAM, AFTER UNDOING ANY
  401. SYSTEM WORK COMPLETED AT THE TIME THE ERROR IS ENCOUNTERED AND ABORTING
  402. THE OPERATION.  ┴N ERROR CODE NUMBER IS STORED IN BINARY IN THE
  403. SINGLE-BYTE "ERRNO" LOCATION. ╘HE SYMBOLIC NAMES FOR THE POSSIBLE ERROR
  404. CODES ARE GIVEN IN THE NEXT SECTION. ╔F NO ERROR OCCURS IN A SYSTEM
  405. CALL, THE CARRY FLAG WILL BE CLEARED ON RETURN FROM THE CALL.  ╬OTE THAT
  406. NOT ALL SYSTEM CALLS CAN RUN INTO ERRORS, SO NOT ALL SET THE CARRY FLAG
  407. ACCORDINGLY.
  408.  
  409. ╔─: "ACE╔─" IS A TWO-BYTE VARIABLE.  ╔TS PURPOSE IS TO ALLOW USER
  410. PROGRAMS TO BE SURE THAT THEY ARE EXECUTING ON TOP OF ┴├┼.  ╘HE LOW BYTE
  411. (I.E., THE FIRST BYTE) MUST BE EQUAL TO THE SYMBOLIC CONSTANT "ACE╔─1",
  412. AND THE HIGH, "ACE╔─2". ╘HIS WILL ALLOW ┴├┼ APPLICATIONS TO INFORM IDIOT
  413. USERS THAT THEY CANNOT SIMPLY ┬╧╧╘ THE PROGRAM FROM ┬┴╙╔├, BUT RATHER
  414. THEY MUST RUN ┴├┼ FIRST.
  415.  
  416. ┴╥╟├: "ACE┴RGC" IS A TWO-BYTE UNSIGNED NUMBER.  ╔T GIVES THE NUMBER OF
  417. ARGUMENTS PASSED TO THE APPLICATION BY THE PROGRAM (USUALLY THE COMMAND
  418. SHELL) THAT CALLED THE APPLICATION.  ╘HE FIRST ARGUMENT IS ALWAYS THE
  419. NAME OF THE APPLICATION PROGRAM, SO THE COUNT WILL ALWAYS BE AT LEAST
  420. ONE.  ╧THER ARGUMENTS ARE OPTIONAL.
  421.  
  422. ┴╥╟╓: "ACE┴RGV" IS A TWO-BYTE ╥┴═0 POINTER.  ╨AY ATTENTION.  ╘HIS
  423. POINTER POINTS TO THE FIRST ENTRY OF AN ARRAY OF TWO-BYTE POINTERS WHICH
  424. POINT TO THE NULL-TERMINATED STRINGS THAT ARE THE ARGUMENTS PASSED TO
  425. THE APPLICATION PROGRAM BY THE CALLER.  (┴ NULL-TERMINATED STRING IS ONE
  426. THAT ENDS WITH A ZERO BYTE).  ╘O FIND THE ADDRESS OF THE ╬-TH ARGUMENT
  427. TO AN APPLICATION, MULTIPLY ╬ BY TWO, ADD THE "ACE┴RGV" CONTENTS TO
  428. THAT, AND FETCH THE POINTER FROM THAT ADDRESS.  ╔N THIS SCHEME, THE
  429. EVER-PRESENT APPLICATION NAME IS THE 0-TH ARGUMENT.  ╘HE ARGV[ARGC]
  430. ELEMENT OF THE ARGUMENT VECTOR WILL ALWAYS CONTAIN A VALUE OF $0000, A
  431. NULL POINTER.
  432.  
  433. ═┼═-╘╧╨: "ACE═EM╘OP" IS A TWO-BYTE ╥┴═0 POINTER.  ╘HIS POINTS TO ONE
  434. BYTE PAST THE HIGHEST BYTE THAT THE APPLICATION PROGRAM IS ALLOWED TO
  435. USE.  ┴LL APPLICATION PROGRAMS ARE LOADED INTO MEMORY AT ADDRESS
  436. "ACE┴PP┴DDRESS" (NEXT SECTION), AND ALL MEMORY BETWEEN THE END OF THE
  437. PROGAM CODE AND "ACE═EM╘OP" CAN BE USED FOR TEMPORARY VARIABLES, FILE
  438. BUFFERS, ETC.  ╘HE MAIN PROBLEM WITH THIS APPROACH IS THAT THERE ARE NO
  439. GUARANTEES ABOUT HOW MUCH MEMORY YOUR APPLICATION WILL GET TO PLAY WITH.
  440. ═ANY APPLICATIONS, SUCH AS SIMPLE FILE UTILITIES, CAN SIMPLY USE ALL
  441. AVAILABLE MEMORY FOR A FILE BUFFER, BUT OTHER PROGRAMS, SUCH AS A FILE
  442. COMPRESSOR, MAY HAVE MUCH GREATER DEMAND FOR "NEAR" MEMORY.  [╬OTE: THIS
  443. VARIABLE HAS A DIFFERENT NAME IN ╥ELEASE #9].
  444.  
  445. ╙╚┼╠╠-╨┴╘╚: "ACE╙HELL╨ATH" IS A TWO-BYTE ╥┴═0 POINTER.  ╘HIS POINTS TO
  446. THE PAGE OF MEMORY THAT STORES THE PATHNAMES OF DIRECTORIES TO SEARCH
  447. THROUGH IN ORDER TO FIND EXECUTABLE FILES.  ┼ACH PATHNAME IS STORED AS A
  448. NULL-TERMINATED STRING, AND THE LIST IS TERMINATED BY AN EMPTY STRING
  449. (CONTAINING ONLY THE ZERO CHARACTER).  ╘HIS IS INTENDED TO BE USED BY
  450. THE SHELL PROGRAM, OR ANY OTHER PROGRAM THAT IS SO INCLINED, TO EXAMINE
  451. OR ALTER THE SEARCH PATH.  ╘HE SEARCH PATHS SPECIFIED IN THE PATH PAGE
  452. ARE GLOBAL VARIABLES AND ARE USED BY ALL PROGRAMS THAT MAKE THE "EXEC"
  453. SYSTEM CALL.  ╘HIS MECHANISM FOR READING/ALTERING THE EXECUTABLE SEARCH
  454. PATH MAY BE CHANGED IN THE FUTURE.
  455.  
  456. ╙╚┼╠╠-┴╠╔┴╙: "ACE╙HELL┴LIAS" IS A TWO-BYTE ╥┴═0 POINTER.  ╘HIS POINTS TO
  457. THE PAGE OF MEMORY THAT STORES THE ALIASES TO BE USED WITH THE COMMAND
  458. SHELL.  ┴N ALIAS IS A STRING THAT IS SUBSTITUTED IN THE PLACE OF A
  459. COMMAND NAME ON A SHELL COMMAND LINE WHENEVER A CERTAIN COMMAND NAME
  460. COMES UP.  ╞OR EXAMPLE, YOU MIGHT SPECIFY IF THE USER ENTERS THE COMMAND
  461. "LIST A:" THAT THE COMMAND NAME "LIST" BE STRING-REPLACED WITH "CLS;XLS
  462. -L".  ┼ACH ALIAS IS STORED WITH THE COMMAND NAME FIRST, FOLLOWED BY AN
  463. EQUALS CHARACTER ("="), FOLLOWED BY THE STRING TO SUBSTITUTE, FOLLOWED
  464. BY A ZERO.  ╘HE ALIAS LIST IS TERMINATED BY AN EMPTY STRING.  ╘HIS
  465. MECHANISM MAY BE EXTENDED IN THE FUTURE TO ALLOW MULTIPLE PAGES OF
  466. ALIASES, OR MAY BE CHANGED COMPLETELY.
  467.  
  468. ├╒╥-─╔╥-╬┴═┼: "ACE├UR─IR╬AME" IS A TWO-BYTE ╥┴═0 POINTER.  ╔T POINTS TO
  469. THE NULL-TERMINATED STRING INDICATING THE CURRENT DIRECTORY.  ╘HE USER
  470. IS NOT SUPPOSED TO MODIFY THIS VALUE, AND THE VALUE WILL NOT ALWAYS GIVE
  471. A FULL PATHNAME.  ╘HE IMPLEMENTATION OF THIS FEATURE MAY NEED TO CHANGE
  472. IN FUTURE VERSIONS OF ┴├┼.
  473.  
  474. ┴├┼-┼╪╔╘-─┴╘┴: "ACE┼XIT─ATA" IS A TWO-BYTE ╥┴═0 POINTER.  ╔T POINTS TO
  475. THE 256-BYTE BUFFER ALLOCATED FOR USER PROGRAMS TO GIVE DETAILED RETURN
  476. INFORMATION UPON EXITING BACK TO THEIR PARENT PROGRAM.  ╙EE THE "EXIT"
  477. SYSTEM CALL.  ╒SER PROGRAMS ARE ALLOWED TO READ AND WRITE THIS STORAGE.
  478. ┴N EXAMPLE USE OF THIS FEATURE WOULD BE A COMPILER PROGRAM RETURNING THE
  479. LINE NUMBER AND CHARACTER POSITION, AND DESCRIPTION OF A COMPILATION
  480. ERROR TO A TEXT EDITOR, SO THE EDITOR CAN POSITION THE CURSOR AND
  481. DISPLAY THE ERROR MESSAGE FOR USER CONVENIENCE.  ╘HE IMPLEMENTATION OF
  482. THIS FEATURE MAY NEED TO CHANGE IN FUTURE VERSIONS OF ┴├┼.
  483.  
  484. ─╔╥┼╬╘-┬╒╞╞┼╥: "ACE─IRENT┬UFFER" IS A BUFFER USED FOR STORING DIRECTORY
  485. INFORMATION READ WITH THE "DIRREAD" SYSTEM CALL, AND IS
  486. "ACE─IRENT╠ENGTH" BYTES LONG.  ╧NLY A SINGLE DIRECTORY ENTRY IS
  487. (LOGICALLY) READ FROM DISK AT A TIME.  ╘HE INDIVIDUAL FIELDS OF A READ
  488. DIRECTORY ENTRY ARE ACCESSED BY THE FIELDS DESCRIBED NEXT.  ╘HIS FIELD
  489. IS ALSO USED FOR RETURNING DISK NAME INFORMATION AND THE NUMBER OF BYTES
  490. FREE ON A DISK DRIVE (SEE THE "DIRREAD" SYSTEM CALL).
  491.  
  492. ─╔╥┼╬╘-┬┘╘┼╙: "ACE─IRENT┬YTES" IS A FOUR-BYTE (32-BIT) UNSIGNED FIELD.
  493. ┴S ALWAYS, THE BYTES ARE ADDRESSED FROM LEAST SIGNIFICANT TO MOST
  494. SIGNIFICANT. ╘HIS FIELD GIVES THE NUMBER OF BYTES IN THE FILE.  ╬OTE
  495. THAT THIS VALUE MAY NOT BE EXACT, SINCE ├OMMODORE DECIDED TO STORE SIZES
  496. IN DISK BLOCKS RATHER THAN BYTES.  ╞OR DEVICES THAT REPORT ONLY BLOCK
  497. COUNTS (I.E., EVERY DISK DEVICE CURRENTLY SUPPORTED), THE NUMBER OF
  498. BYTES RETURNED IS THE NUMBER OF BLOCKS MULTIPLIED BY 254.  ╘HIS FIELD,
  499. AS WELL AND THE OTHER DIRENT FIELDS ARE ABSOLUTE ADDRESSES, NOT OFFSETS
  500. FROM ACE─IRENT┬UFFER.
  501.  
  502. ─╔╥┼╬╘-─┴╘┼: "ACE─IRENT─ATE" IS AN EIGHT-BYTE ARRAY OF BINARY CODED
  503. DECIMAL VALUES, STORED FROM MOST SIGNIFICANT DIGITS TO LEAST
  504. SIGNIFICANT.  ╘HE FIRST BYTE CONTAINS THE ┬├─ CENTURY, THE SECOND THE
  505. YEAR, AND SO ON, AND THE LAST BYTE CONTAINS THE NUMBER OF TENTHS OF
  506. SECONDS IN ITS MOST SIGNIFICANT NYBBLE AND A CODE FOR THE DAY-OF-WEEK IN
  507. ITS LEAST SIGNIFICANT NYBBLE.  ╙UNDAY HAS CODE 1, ═ONDAY 2, ETC.,
  508. ╙ATURDAY 7, AND A CODE OF 0 MEANS "UNKNOWN".  ╘HIS IS THE STANDARD
  509. FORMAT FOR ALL DATES USED IN ┴├┼.  ╘HIS FORMAT IS ABSTRACTED AS
  510. "┘┘:┘┘:══:──:╚╚:══:╙╙:╘╫".  ╞OR DISK DEVICES THAT DON'T SUPPORT DATES,
  511. THIS FIELD WILL BE SET TO ALL ZEROES, WHICH CAN BE CONVENIENTLY
  512. INTERPRETED AS THE ╬╒╠╠ DATE, NEGATIVE INFINITY, OR AS THE TIME THAT
  513. ╩.├. WAS A SEVEN-YEAR-OLD BOY.
  514.  
  515. ─╔╥┼╬╘-╘┘╨┼: "ACE─IRENT╘YPE" IS A THREE-CHARACTER (FOUR-BYTE)
  516. NULL-TERMINATED STRING.  ╔T INDICATES WHAT TYPE THE FILE IS, IN
  517. LOWERCASE ╨┼╘╙├╔╔.  ╙TANDARD TYPES SUCH AS "╙┼╤" AND "╨╥╟" WILL BE
  518. RETURNED, AS WELL AND OTHER POSSIBILITIES FOR CUSTOM DEVICE DRIVERS.
  519.  
  520. ─╔╥┼╬╘-╞╠┴╟╙: "ACE─IRENT╞LAGS" IS A ONE-BYTE FIELD THAT IS INTERPRETED
  521. AS CONSISTING OF EIGHT INDEPENDENT ONE-BIT FIELDS.  ╘HE ABSTRACT VIEW OF
  522. THE FIELDS IS "DRWX*-ET".  "D" MEANS THAT THE ITEM IS A SUBDIRECTORY
  523. (OTHERWISE IT IS A REGULAR FILE), "R" MEANS THE ITEM IS READABLE, "W"
  524. MEANS THE ITEM IS WRITABLE, AND "X" MEANS THE ITEM IS EXECUTABLE.  ╘HE
  525. "X" OPTION IS REALLY NOT SUPPORTED CURRENTLY.  "*" MEANS THE ITEM IS
  526. IMPROPERLY CLOSED (A "SPLAT" FILE IN ├OMMODORE-─╧╙ TERMINOLOGY).  ╘HE
  527. "-" FIELD IS CURRENTLY UNDEFINED.  "E" MEANS THAT THE VALUE GIVEN IN THE
  528. "ACE─IRENT┬YTES" FIELD IS ACTUALLY EXACT, AND "T" MEANS THE FILE SHOULD
  529. BE INTERPRETED AS BEING A "TEXT" FILE (OTHERWISE, ITS TYPE IS EITHER
  530. BINARY OR UNKNOWN).  ╘HE BIT FIELDS ARE ALL BOOLEANS; A VALUE OF "1"
  531. MEANS TRUE, "0", FALSE.  ╘HE "D" BIT OCCUPIES THE 128-BIT POSITION, ETC.
  532.  
  533. ─╔╥┼╬╘-╬┴═┼-╠┼╬: "ACE─IRENT╬AME╠EN" IS A ONE-BYTE NUMBER.  ╔T GIVES THE
  534. NUMBER OF CHARACTERS IN THE FILENAME.  ╔T IS PRESENT FOR CONVENIENCE.
  535.  
  536. ─╔╥┼╬╘-╬┴═┼: "ACE─IRENT╬AME" IS A 16-CHARACTER (17-BYTE) NULL-TERMINATED
  537. CHARACTER STRING FIELD.  ╔T GIVES THE NAME OF THE FILE OR DIRECTORY OR
  538. DISK. ╞ILENAMES USED WITH ┴├┼ ARE LIMITED TO 16 CHARACTERS.
  539.  
  540. 2.3. ╙┘╙╘┼═ ├╧╬╙╘┴╬╘╙
  541.  
  542. ╘HERE ARE SEVERAL SYMBOLIC CONSTANTS THAT ARE USED WITH THE ┴├┼ SYSTEM
  543. INTERFACE:
  544.  
  545. ╙┘═┬╧╠                   ─┼╙├╥╔╨╘╔╧╬
  546. -------------------      -------------------------
  547. ACE┴PP┴DDRESS            THE START ADDRESS OF APPLICATIONS
  548. ACE╔─1                   THE ID CHARACTERS USED TO IDENTIFY ┴├┼ APPLICATIONS
  549. ACE╔─2                   ...
  550. ACE╔─3                   ...
  551. ACE═EM╬ULL               THE FAR MEMORY TYPE CODE USED TO INDICATE NULL PTRS
  552. ACE═EM╥┼╒                FAR MEM TYPE CODE FOR ╥AM ┼XPANSION ╒NIT MEMORY
  553. ACE═EM╔NTERNAL           FAR MEM TYPE CODE FOR INTERNAL MEMORY
  554. ACE═EM╥╠╥┼╒              FAR MEM TYPE CODE FOR ╥┼╒ MEMORY ACCESSED THRU ╥┴═╠INK
  555. ACE═EM╥╠                 FAR MEM TYPE CODE FOR DIRECT-ACCESS ╥┴═╠INK MEMORY
  556. ACE┼RR╙TOPPED            ERROR CODE FOR SYSCALL ABORTED BY ╙╘╧╨ KEY
  557. ACE┼RR╘OO═ANY╞ILES       ERR: TOO MANY FILES ALREADY OPENED TO OPEN ANOTHER
  558. ACE┼RR╞ILE╧PEN           ERR: DON'T KNOW WHAT THIS MEANS
  559. ACE┼RR╞ILE╬OT╧PEN        ERR: THE GIVEN FILE DESCRIPTOR IS NOT ACTUALLY OPEN
  560. ACE┼RR╞ILE╬OT╞OUND       ERR: NAMED FILE TO OPEN FOR READING DOES NOT EXIST
  561. ACE┼RR─EVICE╬OT╨RESENT   ERR: THE SPECIFIED PHYSICAL DEVICE IS NOT ONLINE
  562. ACE┼RR╞ILE╬OT╔NPUT       ERR: FILE CANNOT BE OPENED FOR READING
  563. ACE┼RR╞ILE╬OT╧UTPUT      ERR: FILE CANNOT BE OPENED FOR WRITING
  564. ACE┼RR═ISSING╞ILENAME    ERR: PATHNAME COMPONENT IS THE NULL STRING
  565. ACE┼RR╔LLEGAL─EVICE      ERR: THE SPECIFIED DEVICE CANNOT DO WHAT YOU WANT
  566. ACE┼RR╫RITE╨ROTECT       ERR: TRYING TO WRITE TO A DISK THAT IS WRITE-PROTECTED
  567. ACE┼RR╞ILE┼XISTS         ERR: TRYING TO OPEN FOR WRITING FILE THAT EXISTS
  568. ACE┼RR╞ILE╘YPE═ISMATCH   ERR: YOU SPECIFIED THE FILE TYPE INCORRECTLY
  569. ACE┼RR╬O├HANNEL          ERR: TOO MANY OPEN FILES ON DISK DRIVE TO OPEN ANOTHER
  570. ACE┼RR╔NSUFFICIENT═EMORY ERR: ┴├┼ COULD NOT ALLOCATE THE MEMORY YOU REQUESTED
  571. ACE┼RR╧PEN─IRECTORY      ERR: YOU ARE TRYING TO OPEN A DIR AS IF IT WERE A FILE
  572. ACE┼RR─ISK╧NLY╧PERATION  ERR: TRYING TO PERFORM DISK-ONLY OP ON CHAR DEVICE
  573. ACE┼RR╬ULL╨OINTER        ERR: TRYING TO DEREFERENCE A NULL FAR POINTER
  574. ACE┼RR╔NVALID╞REE╨ARMS   ERR: BAD CALL TO "PAGEFREE": MISALIGNED/WRONG SIZE
  575. ACE┼RR╞REE╬OT╧WNED       ERR: TRYING TO FREE FAR MEMORY YOU DON'T OWN
  576. STDIN                    FILE DESCRIPTOR RESERVED FOR STDIN INPUT STREAM
  577. STDOUT                   FILE DESCRIPTOR RESERVED FOR STDOUT OUTPUT STREAM
  578. STDERR                   FILE DESCRIPTOR RESERVED FOR STDERR OUTPUT STREAM
  579.  
  580. "ACE┴PP┴DDRESS", AS DISCUSSED BEFORE, IS THE ADDRESS THAT APPLICATION
  581. PROGRAMS ARE LOADED INTO MEMORY AT.  ╘HEY MUST, OF COURSE, BE COMPILED
  582. TO EXECUTE STARTING AT THIS ADDRESS.
  583.  
  584. ╘HE "ACE═EM" GROUP OF CONSTANTS ARE FOR USE WITH THE "PAGEALLOC" SYSTEM
  585. CALL, EXCEPT FOR "ACE═EM╬ULL", WHICH MAY BE USED BY APPLICATION PROGRAMS
  586. FOR INDICATING NULL FAR POINTERS.  ╘HE "PAGEALLOC" CALL ALLOWS YOU TO
  587. SPECIFY WHAT TYPES OF MEMORY YOU ARE WILLING TO ACCEPT.  ╘HIS IS
  588. IMPORTANT BECAUSE THE DIFFERENCE TYPES OF MEMORY HAVE DIFFERENT
  589. PERFORMANCE CHARACTERISTICS.  ┴├┼ WILL TRY TO GIVE YOU THE FASTEST
  590. MEMORY THAT IS AVAILABLE.  ╥AM ┼XPANSION ╒NIT MEMORY HAS STARTUP AND
  591. BYTE-TRANSFER TIMES OF ABOUT 60 US (MICROSECONDS) AND 1 US,
  592. RESPECTIVELY.  ╘HIS IS THE FASTEST TYPE OF FAR MEMORY.  ╔NTERNAL MEMORY
  593. HAS A STARTUP TIME OF 24 US AND A BYTE-TRANSFER TIME OF BETWEEN 7 AND 14
  594. US (DEPENDING ON WHETHER ACCESSING ╥┴═0 OR ╥┴═1+).  ╥┼╒ MEMORY ACCESSED
  595. THROUGH A ╥┴═╠INK HAS A TERRIBLE STARTUP TIME OF 1000 US AND A
  596. BYTE-TRANSFER TIME OF 2 US.  ─IRECT-ACCESS ╥┴═╠INK MEMORY HAS A STARTUP
  597. TIME OF 1000 US AND A BYTE-TRANSFER TIME OF 16 US.  ┴LL THESE TIMES ARE
  598. FOR THE ├128 IN 2 ═╚Z MODE.
  599.  
  600. ╘HE "ACE┼RR" GROUP GIVES THE ERROR CODES RETURNED BY SYSTEM CALLS.  ╘HE
  601. ERROR CODES ARE RETURNED IN THE "ERRNO" VARIABLE.  ╬OT ALL POSSIBLE
  602. ERROR CODES FROM ├OMMODORE DISK DRIVES ARE COVERED, BUT THE IMPORTANT
  603. ONES ARE.  ╞INALLY, THE "STD" FILES GROUP GIVE THE SYMBOLIC FILE
  604. DESCRIPTOR IDENTIFIERS OF THE DEFAULT INPUT, OUTPUT, AND ERROR OUTPUT
  605. FILE STREAMS.
  606.  
  607. 2.4. ╙┘╙╘┼═ ├┴╠╠╙
  608.  
  609. ┴LL SYSTEM CALLS ARE CALLED BY SETTING UP ARGUMENTS IN SPECIFIED
  610. PROCESSOR REGISTERS AND MEMORY LOCATIONS, EXECUTING A ╩╙╥ TO THE SYSTEM
  611. CALL ADDRESS, AND PULLING THE RETURN VALUES OUT OF PROCESSOR REGISTERS
  612. AND MEMORY LOCATIONS.
  613.  
  614. 2.1. ╞╔╠┼ ├┴╠╠╙
  615.  
  616. ╬┴═┼   :  OPEN
  617. ╨╒╥╨╧╙┼:  OPEN A FILE
  618. ┴╥╟╙   :  (ZP) = PATHNAME
  619.           .┴   = FILE MODE ("R", "W", OR "A")
  620. ╥┼╘╒╥╬╙:  .┴   = FILE DESCRIPTOR NUMBER
  621.           .├╙  = ERROR OCCURRED FLAG
  622. ┴╠╘┼╥╙ :  .╪, .┘, ERRNO
  623.  
  624. ╧PENS A FILE.  ╘HE NAME OF THE FILE IS GIVEN BY A POINTER TO A
  625. NULL-TERMINATED STRING, AND MAY CONTAIN DEVICE NAMES AND PATHNAMES AS
  626. SPECIFIED IN THE ┴├┼ USER DOCUMENTATION.  ╘HE FILE MODE IS A ╨┼╘╙├╔╔
  627. CHARACTER.  "R" MEANS TO OPEN THE FILE FOR READING, "W" MEANS TO OPEN
  628. THE FILE FOR WRITING, AND "A" MEANS TO OPEN THE FILE FOR APPENDING
  629. (WRITING, STARTING AT THE END OF THE FILE).  ┴N ERROR WILL BE RETURNED
  630. IF YOU ATTEMPT TO OPEN FOR READING OR APPENDING A FILE THAT DOES NOT
  631. EXIST, OR IF YOU ATTEMPT TO OPEN FOR WRITING A FILE THAT DOES ALREADY
  632. EXIST.  ╔F YOU WISH TO OVERWRITE AN EXISTING FILE, YOU WILL HAVE TO CALL
  633. "REMOVE" TO DELETE THE OLD VERSION BEFORE OPENING THE NEW VERSION FOR
  634. WRITING.
  635.  
  636. ╘HE FUNCTION RETURNS A FILE DESCRIPTOR NUMBER, WHICH IS A SMALL UNSIGNED
  637. INTEGER THAT IS USED WITH OTHER FILE CALLS TO SPECIFY THE FILE THAT HAS
  638. BEEN OPENED.  ╞ILE DESCRIPTORS NUMBERED 0, 1, AND 2 ARE USED FOR STDIN,
  639. STDOUT, AND STDERR, RESPECTIVELY.  ╘HE FILE DESCRIPTOR RETURNED WILL BE
  640. THE MINIMUM NUMBER THAT IS NOT CURRENTLY IN USE.  ╘HESE NUMBERS ARE
  641. SYSTEM-WIDE (RATHER THAN LOCAL TO A PROCESS AS IN ╒NIX), AND THIS HAS
  642. SOME IMPLICATIONS FOR ╔/╧ REDIRECTION (SEE THE "FDSWAP" CALL BELOW).
  643.  
  644. ╥ESTRICTIONS: ONLY SO MANY ╦ERNAL FILES ALLOWED TO BE OPEN ON A DISK
  645. DEVICE, AND THERE IS A SYSTEM MAXIMUM OF OPEN FILES.  ┘OU WILL GET A
  646. "TOO MANY FILES" ERROR IF YOU EVER EXCEED THIS LIMIT.  ┴LSO, BECAUSE OF
  647. THE NATURE OF ├OMMODORE-─╧╙, THERE MAY BE EVEN TIGHTER RESTRICTIONS ON
  648. THE NUMBER OF FILES THAT CAN BE SIMULTANEOUSLY OPEN ON A SINGLE DISK
  649. DEVICE, RESULTING IN A "NO CHANNEL" ERROR.  ╬OTE THAT THIS CALL CHECKS
  650. THE STATUS CHANNEL OF ├OMMODORE DISK DRIVES ON EACH OPEN, SO YOU DON'T
  651. HAVE TO (AND SHOULD NOT ANYWAY).
  652.  
  653. ╔F THE CURRENT PROGRAM EXITS EITHER BY CALLING "EXIT" OR SIMPLY BY DOING
  654. THE LAST ╥╘╙, ALL FILES THAT WERE OPENED BY THE PROGRAM AND ARE STILL
  655. OPEN WILL BE AUTOMATICALLY CLOSED BY THE SYSTEM BEFORE RETURNING TO THE
  656. PARENT PROGRAM.
  657.  
  658. ╬┴═┼   :  CLOSE
  659. ╨╒╥╨╧╙┼:  CLOSE AN OPEN FILE
  660. ┴╥╟╙   :  .┴   = ╞ILE DESCRIPTOR NUMBER
  661. ╥┼╘╒╥╬╙:  .├╙  = ERROR OCCURRED FLAG
  662. ┴╠╘┼╥╙ :  .┴, .╪, .┘, ERRNO
  663.  
  664. ├LOSES AN OPEN FILE.  ╬OT MUCH TO SAY ABOUT THIS ONE.
  665.  
  666. ╬┴═┼   :  READ
  667. ╨╒╥╨╧╙┼:  READ DATA FROM AN OPEN FILE
  668. ┴╥╟╙   :  .╪   = ╞ILE DESCRIPTOR NUMBER
  669.           (ZP) = POINTER TO BUFFER TO STORE DATA INTO
  670.           .┴┘  = MAXIMUM NUMBER OF BYTES TO READ
  671. ╥┼╘╒╥╬╙:  (ZW) = .┴┘=NUMBER OF BYTES ACTUALLY READ IN
  672.           .├╙  = ERROR OCCURRED FLAG
  673.           .┌╙  = ┼╧╞ REACHED FLAG
  674. ┴╠╘┼╥╙ :  .╪, ERRNO
  675.  
  676. ╥EADS DATA FROM THE CURRENT POSITION OF AN OPEN FILE.  ╒P TO THE
  677. SPECIFIED MAXIMUM NUMBER OF BYTES WILL BE READ.  ┘OU SHOULD NOT GIVE A
  678. MAXIMUM OF ZERO BYTES, OR YOU MAY MISINTERPRET AN ┼╧╞ (END OF FILE).
  679. ╘HE BUFFER MUST BE AT LEAST THE SIZE OF THE MAXIMUM NUMBER OF BYTES TO
  680. READ.  ╘HE DATA ARE NOT INTERPRETED IN ANY WAY, SO IT IS THE
  681. PROGRAMMER'S RESPONSIBILITY TO SEARCH FOR CARRIAGE RETURN CHARACTERS TO
  682. LOCATE LINES OF INPUT, IF HE SO DESIRES. ╚OWEVER, FOR THE CONSOLE THE
  683. INPUT IS NATURALLY DIVIDED UP INTO LINES, SO EACH CALL WILL RETURN AN
  684. ENTIRE LINE OF BYTES IF THE BUFFER IS LARGE ENOUGH.  ╘HERE ARE NO
  685. GUARANTEES ABOUT THE NUMBER OF BYTES THAT WILL BE RETURNED, EXCEPT THAT
  686. IT WILL BE BETWEEN 1 AND THE BUFFER SIZE.  ╙O, IF YOU WISH TO READ A
  687. CERTAIN NUMBER OF BYTES, YOU MAY HAVE TO MAKE MULTIPLE READ CALLS.
  688.  
  689. ╘HE CALL RETURNS THE NUMBER OF BYTES READ IN BOTH THE .┴┘ REGISTER PAIR
  690. AND IN (ZW), FOR ADDED CONVENIENCE.  [╬OTE: IN ┴├┼ ╥ELEASE #9, THE
  691. NUMBER OF BYTES READ ARE RETURNED ONLY IN THE .┴┘ REGISTERS, NOT IN
  692. (ZW).]  ┴ RETURN OF ZERO BYTES READ MEANS THAT THE END OF THE FILE HAS
  693. BEEN REACHED.  ┴N ATTEMPT TO READ BEYOND THE END OF FILE WILL SIMPLY
  694. GIVE ANOTHER ┼╧╞ RETURN.  ┼ND OF FILE IS ALSO RETURNED IN THE .┌ FLAG OF
  695. THE PROCESSOR.
  696.  
  697. ╬┴═┼   :  WRITE
  698. ╨╒╥╨╧╙┼:  WRITE DATA TO AN OPEN FILE
  699. ┴╥╟╙   :  .╪   = FILE DESCRIPTOR NUMBER
  700.           (ZP) = POINTER TO DATA TO BE WRITTEN
  701.           .┴┘  = LENGTH OF DATA TO BE WRITTEN IN BYTES
  702. ╥┼╘╒╥╬╙:  .├╙  = ERROR OCCURRED
  703. ┴╠╘┼╥╙ :  .┴, .╪, .┘, ERRNO
  704.  
  705. ╫RITES DATA AT THE CURRENT POSITION OF AN OPEN FILE.  [╬OTE: ┴├┼ ╥ELEASE
  706. #9 ALSO ALTERS LOCATIONS (ZW) WHEN WRITING TO THE CONSOLE.  ╘HIS PROBLEM
  707. WILL BE CORRECTED.]
  708.  
  709. ╬┴═┼   :  FASTOPEN
  710. ╨╒╥╨╧╙┼:  OPEN A FILE FOR FAST READING
  711. ┴╥╟╙   :  (ZP) = ╬AME
  712.           .┴   = FILE MODE (MUST BE "R")
  713. ╥┼╘╒╥╬╙:  .┴   = FILE DESCRIPTOR NUMBER
  714.           .├╙  = ERROR OCCURRED FLAG
  715. ┴╠╘┼╥╙ :  .╪, .┘, ERRNO
  716.  
  717. ╘HIS PERFORMS THE SAME FUNCTION AS THE REGULAR "OPEN" CALL, EXCEPT THIS
  718. STYLE OF FILE ACCESSING WILL ALLOW FILES TO BE READ MUCH FASTER THAN THE
  719. OTHER.  ╧N DEVICES THAT ARE SO EQUIPPED, THE "FASTLOAD" BURST COMMAND IS
  720. USED (SIMILAR SHORTCUTS MAY BE POSSIBLE WITH OTHER DEVICES TOO).  ╘HE
  721. DRAWBACK OF THIS INCREASED SPEED IS THAT NO OTHER DEVICE ╔/╧ CAN TAKE
  722. PLACE WHILE A FILE IS OPENED FOR "FAST" ACCESS, NOT EVEN TO OTHER
  723. DEVICES, EXCEPT FOR OUTPUT TO THE CONSOLE.  ╧THER FILES CAN BE OPEN,
  724. JUST NOT ACCESSED.  ┘OU ALSO CANNOT OPEN MORE THAN ONE "FAST" FILE AT A
  725. TIME.  ╔NTERRUPTS WILL BE DISABLED WHILE A FILE IS OPEN FOR FAST
  726. ACCESSING, SO THE USER CANNOT RE-ENABLE THEM, FOR TECHNICAL REASONS.
  727. ╘HE ARGUMENTS TO THIS CALL ARE EXACTLY THE SAME AS THE REGULAR "OPEN" TO
  728. MAKE IT EASY TO SWITCH FROM USING ONE TO THE OTHER.  [╬OTE: THESE "FAST"
  729. CALLS DO NOT EXIST IN ╥ELEASE #9].
  730.  
  731. ╬┴═┼   :  FASTCLOSE
  732. ╨╒╥╨╧╙┼:  CLOSE THE FILE THAT WAS OPENED FOR FAST READING
  733. ┴╥╟╙   :  .┴   = ╞ILE DESCRIPTOR NUMBER
  734. ╥┼╘╒╥╬╙:  .├╙  = ERROR OCCURRED FLAG
  735. ┴╠╘┼╥╙ :  .┴, .╪, .┘, ERRNO
  736.  
  737. ├LOSES THE FILE THAT WAS OPENED FOR FAST READING.
  738.  
  739. ╬┴═┼   :  FASTREAD
  740. ╨╒╥╨╧╙┼:  READ DATA FROM THE FILE OPENED FOR FAST READING
  741. ┴╥╟╙   :  .╪   = ╞ILE DESCRIPTOR NUMBER
  742.           (ZP) = POINTER TO BUFFER TO STORE DATA INTO
  743.           .┴┘  = MAXIMUM NUMBER OF BYTES TO READ
  744. ╥┼╘╒╥╬╙:  (ZW) = .┴┘=NUMBER OF BYTES ACTUALLY READ IN
  745.           .├╙  = ERROR OCCURRED FLAG
  746.           .┌╙  = ┼╧╞ REACHED FLAG
  747. ┴╠╘┼╥╙ :  .╪, ERRNO
  748.  
  749. ╥EAD DATA FROM THE (ONE) FILE THAT IS CURRENTLY OPENED FOR "FAST"
  750. READING. ╘HE ARGUMENTS AND SEMANTICS ARE EQUIVALENT TO THE REGULAR
  751. "READ" CALL.
  752.  
  753. ╬┴═┼   :  BLOAD
  754. ╨╒╥╨╧╙┼:  BINARY LOAD
  755. ┴╥╟╙   :  (ZP) = PATHNAME
  756.           .┴┘  = ADDRESS TO LOAD FILE
  757.           (ZW) = HIGHEST ADDRESS THAT FILE MAY OCCUPY, PLUS ONE
  758. ╥┼╘╒╥╬╙:  .┴┘  = END ADDRESS OF LOAD, PLUS ONE
  759.           .├╙  = ERROR OCCURRED FLAG
  760. ┴╠╘┼╥╙ :  .╪, ERRNO
  761.  
  762. ┬INARY-LOAD A FILE DIRECTLY INTO MEMORY.  ╔F THE FILE WILL NOT FIT INTO
  763. THE SPECIFIED SPACE, AN ERROR WILL BE RETURNED AND THE LOAD TRUNCATED IF
  764. THE DEVICE SUPPORTS TRUNCATION; OTHERWISE, IMPORTANT DATA MAY BE
  765. OVERWRITTEN.
  766.  
  767. ╬┴═┼   :  REMOVE
  768. ╨╒╥╨╧╙┼:  DELETE A FILE
  769. ┴╥╟╙   :  (ZP) = PATHNAME
  770. ╥┼╘╒╥╬╙:  .├╙  = ERROR OCCURRED FLAG
  771. ┴╠╘┼╥╙ :  .┴, .╪, .┘, ERRNO
  772.  
  773. ─ELETE THE NAMED FILE.
  774.  
  775. ╬┴═┼   :  RENAME
  776. ╨╒╥╨╧╙┼:  RENAME A FILE OR DIRECTORY
  777. ┴╥╟╙   :  (ZP) = OLD FILENAME
  778.           (ZW) = NEW FILENAME
  779. ╥┼╘╒╥╬╙:  .├╙  = ERROR OCCURRED FLAG
  780. ┴╠╘┼╥╙ :  .┴, .╪, .┘, ERRNO
  781.  
  782. ╥ENAMES A FILE OR DIRECTORY.  ╔F A FILE WITH THE NEW NAME ALREADY
  783. EXISTS, THEN THE OPERATION WILL BE ABORTED AND A "FILE EXISTS" ERROR
  784. WILL BE RETURNED.  ╧N MOST DEVICES, THE FILE TO BE RENAMED MUST BE IN
  785. THE CURRENT DIRECTORY AND THE NEW NAME MAY NOT INCLUDE ANY PATH, JUST A
  786. FILENAME.
  787.  
  788. ╬┴═┼   :  DEVINFO
  789. ╨╒╥╨╧╙┼:  GIVE INFORMATION ABOUT DEVICE
  790. ┴╥╟╙   :  .╪   = FILE DESCRIPTOR NUMBER
  791. ╥┼╘╒╥╬╙:  .┴   = DEVICE TYPE CODE
  792.           .╪   = NUMBER OF COLUMNS ON DEVICE
  793.           .┘   = NUMBER OF ROWS PER "PAGE" OF DEVICE
  794.           .├╙  = ERROR OCCURRED FLAG
  795. ┴╠╘┼╥╙ :  ERRNO
  796.  
  797. ╘HIS CALL RETURNS INFORMATION ABOUT THE DEVICE OF AN OPEN FILE.  ╘HERE
  798. ARE FOUR POSSIBLE VALUES FOR THE DEVICE TYPE CODE: 0==CONSOLE,
  799. 1==CHARACTER-ORIENTED DEVICE, AND 2==DISK DEVICE.  ╘HE NUMBER OF ROWS
  800. AND COLUMNS PER "PAGE" OF THE DEVICE ARE ALSO RETURNED.  ╞OR THE
  801. CONSOLE, THIS WILL BE THE CURRENT WINDOW SIZE.  ╞OR A CHARACTER-ORIENTED
  802. DEVICE, IT WILL BE THE NATURAL SIZE (TYPICALLY 80 COLUMNS BY 66 ROWS),
  803. AND FOR A DISK, IT WILL BE 40 COLUMNS IN 64 MODE OR 80 COLUMNS IN 128
  804. MODE, BOTH BY 66 ROWS.
  805.  
  806. ╬┴═┼   :  FDSWAP
  807. ╨╒╥╨╧╙┼:  SWAP TWO FILE DESCRIPTOR NUMBERS
  808. ┴╥╟╙   :  .╪   = FIRST FILE DESCRIPTOR NUMBER
  809.           .┘   = SECOND FILE DESCRIPTOR NUMBER
  810. ╥┼╘╒╥╬╙:  .├╙  = ERROR OCCURRED FLAG
  811. ┴╠╘┼╥╙ :  .┴, .╪, .┘, ERRNO
  812.  
  813. ╘HIS CALL SWAPS MEANINGS OF TWO FILE DESCRIPTOR NUMBERS.  ╘HE FILE
  814. DESCRIPTORS MAY BE EITHER IN USE OR NOT USE WHEN THE CALL IS MADE.  ╘HIS
  815. CALL IS INTENDED TO BE USED TO REDIRECT THE STDIN, STDOUT, AND STDERR
  816. FILE STREAMS.  ╘O DO THIS, SIMPLY OPEN THE NEW FILE INTENDED TO BE, FOR
  817. EXAMPLE, STDOUT, AND SWAP THE FILE DESCRIPTOR NUMBER RETURNED FROM THE
  818. OPEN WITH FILE DESCRIPTOR NUMBER 1 (STDOUT).  ╨OOF.  ╘HEN CALL YOUR
  819. SUBROUTINE OR EXTERNAL PROGRAM, AND ON RETURN, SWAP THE TWO FILE
  820. DESCRIPTORS BACK, AND CLOSE THE REDIRECTION FILE.
  821.  
  822. 2.2. ─╔╥┼├╘╧╥┘ ├┴╠╠╙
  823.  
  824. ╬┴═┼   :  DIROPEN
  825. ╨╒╥╨╧╙┼:  OPEN A DIRECTORY FOR SCANNING ITS DIRECTORY ENTRIES
  826. ┴╥╟╙   :  (ZP) = DIRECTORY PATHNAME
  827. ╥┼╘╒╥╬╙:  .┴   = FILE DESCRIPTOR NUMBER
  828.           .├╙  = ERROR OCCURRED FLAG
  829. ┴╠╘┼╥╙ :  .╪, .┘, ERRNO
  830.  
  831. ╘HIS CALL OPENS A DIRECTORY FOR READING ITS ENTRIES.  ╔T RETURNS A
  832. "FILE" DESCRIPTOR NUMBER TO YOU TO USE FOR READING SUCCESSIVE DIRECTORY
  833. ENTIRES WITH THE "DIRREAD" CALL.  ╘HE PATHNAME THAT YOU GIVE TO THIS
  834. CALL MUST BE A PROPER DIRECTORY NAME LIKE "A:" OR "C:2//C64/GAMES/:",
  835. ENDING WITH A COLON CHARACTER. ┘OU CAN HAVE DIRECTORIES FROM MULTIPLE
  836. DEVICES OPEN FOR READING AT ONE TIME, BUT YOU CANNOT HAVE THE DIRECTORY
  837. OF ONE DEVICE OPEN MULTIPLE TIMES.  ┴LSO NOTE THAT YOU CANNOT PASS
  838. WILDCARDS TO THIS CALL; YOU WILL RECEIVE THE ENTIRE DIRECTORY LISTING.
  839.  
  840. ╬┴═┼   :  DIRCLOSE
  841. ╨╒╥╨╧╙┼:  CLOSE A DIRECTORY OPENED FOR SCANNING
  842. ┴╥╟╙   :  .┴   = FILE DESCRIPTOR NUMBER
  843. ╥┼╘╒╥╬╙:  .├╙  = ERROR OCCURRED FLAG
  844. ┴╠╘┼╥╙ :  .┴, .╪, .┘, ERRNO
  845.  
  846. ├LOSES A DIRECTORY THAT IS OPEN FOR READING.  ┘OU CAN MAKE THIS CALL AT
  847. ANY POINT WHILE SCANNING A DIRECTORY; YOU DO NOT HAVE TO FINISH SCANNING
  848. AN ENTIRE DIRECTORY FIRST.
  849.  
  850. ╬┴═┼   :  DIRREAD
  851. ╨╒╥╨╧╙┼:  READ THE NEXT DIRECTORY ENTRY FROM AN OPEN DIRECTORY
  852. ┴╥╟╙   :  .╪   = FILE DESCRIPTOR NUMBER
  853. ╥┼╘╒╥╬╙:  .┌   = END OF DIRECTORY FLAG
  854.           .├╙  = ERROR OCCURRED FLAG
  855.           ACE─IRENT┬UFFER = NEW DIRECTORY ENTRY DATA
  856. ┴╠╘┼╥╙ :  .┴, .╪, .┘, ERRNO
  857.  
  858. ╥EADS THE NEXT DIRECTORY ENTRY FROM THE SPECIFIED OPEN DIRECTORY INTO
  859. THE SYSTEM INTERFACE GLOBAL VARIABLE "ACE─IRENT┬UFFER" DESCRIBED
  860. EARLIER.  ┴FTER OPENING A DIRECTORY FOR READING, THE FIRST TIME YOU CALL
  861. THIS ROUTINE, YOU WILL RECEIVE THE NAME OF THE DISK (OR DIRECTORY).  ╘HE
  862. "ACE─IRENT╬AME╠EN" AND "ACE─IRENT╬AME" FIELDS ARE THE ONLY ONES THAT
  863.